<?xml version='1.0' encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <link href="cpip.css" rel="stylesheet" type="text/css" />
    <title>File: /Users/paulross/dev/Python-3.6.2/Include/pyarena.h</title>
  </head>
  <body>
    <h1>File: /Users/paulross/dev/Python-3.6.2/Include/pyarena.h</h1>
    <p>Green shading in the line number column
means the source is part of the translation unit, red means it is conditionally excluded.
Highlighted line numbers link to the translation unit page. Highlighted macros link to
the macro page.</p>
    <pre><a name="1" /><span class="True">       1:</span> <span class="k">/* An arena-like memory interface for the compiler.</span>
<a name="2" /><span class="True">       2:</span> <span class="k"> */</span>
<a name="3" /><span class="True">       3:</span> 
<a name="4" /><span class="True">       4:</span> <span class="f">#</span><span class="n">ifndef</span> <span class="b">Py_LIMITED_API</span>
<a name="5" /><span class="True">       5:</span> <span class="f">#</span><span class="n">ifndef</span> <a href="macros_noref.html#_UHlfUFlBUkVOQV9IXzA_"><span class="b">Py_PYARENA_H</span></a>
<a name="6" /><span class="True">       6:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_noref.html#_UHlfUFlBUkVOQV9IXzA_"><span class="b">Py_PYARENA_H</span></a>
<a name="7" /><span class="True">       7:</span> 
<a name="8" /><span class="False">       8:</span> <span class="f">#</span><span class="n">ifdef</span> <span class="b">__cplusplus</span>
<a name="9" /><span class="False">       9:</span> <span class="m">extern</span> <span class="e">&quot;C&quot;</span> <span class="f">{</span>
<a name="10" /><span class="True">      10:</span> <span class="f">#</span><span class="n">endif</span>
<a name="11" /><span class="True">      11:</span> 
<a name="12" /><span class="True">      12:</span>   <span class="m">typedef</span> <span class="m">struct</span> <span class="b">_arena</span> <span class="b">PyArena</span><span class="f">;</span>
<a name="13" /><span class="True">      13:</span> 
<a name="14" /><span class="True">      14:</span>   <span class="k">/* PyArena_New() and PyArena_Free() create a new arena and free it,</span>
<a name="15" /><span class="True">      15:</span> <span class="k">     respectively.  Once an arena has been created, it can be used</span>
<a name="16" /><span class="True">      16:</span> <span class="k">     to allocate memory via PyArena_Malloc().  Pointers to PyObject can</span>
<a name="17" /><span class="True">      17:</span> <span class="k">     also be registered with the arena via PyArena_AddPyObject(), and the</span>
<a name="18" /><span class="True">      18:</span> <span class="k">     arena will ensure that the PyObjects stay alive at least until</span>
<a name="19" /><span class="True">      19:</span> <span class="k">     PyArena_Free() is called.  When an arena is freed, all the memory it</span>
<a name="20" /><span class="True">      20:</span> <span class="k">     allocated is freed, the arena releases internal references to registered</span>
<a name="21" /><span class="True">      21:</span> <span class="k">     PyObject*, and none of its pointers are valid.</span>
<a name="22" /><span class="True">      22:</span> <span class="k">     XXX (tim) What does &quot;none of its pointers are valid&quot; mean?  Does it</span>
<a name="23" /><span class="True">      23:</span> <span class="k">     XXX mean that pointers previously obtained via PyArena_Malloc() are</span>
<a name="24" /><span class="True">      24:</span> <span class="k">     XXX no longer valid?  (That&apos;s clearly true, but not sure that&apos;s what</span>
<a name="25" /><span class="True">      25:</span> <span class="k">     XXX the text is trying to say.)</span>
<a name="26" /><span class="True">      26:</span> <span class="k"></span>
<a name="27" /><span class="True">      27:</span> <span class="k">     PyArena_New() returns an arena pointer.  On error, it</span>
<a name="28" /><span class="True">      28:</span> <span class="k">     returns a negative number and sets an exception.</span>
<a name="29" /><span class="True">      29:</span> <span class="k">     XXX (tim):  Not true.  On error, PyArena_New() actually returns NULL,</span>
<a name="30" /><span class="True">      30:</span> <span class="k">     XXX and looks like it may or may not set an exception (e.g., if the</span>
<a name="31" /><span class="True">      31:</span> <span class="k">     XXX internal PyList_New(0) returns NULL, PyArena_New() passes that on</span>
<a name="32" /><span class="True">      32:</span> <span class="k">     XXX and an exception is set; OTOH, if the internal</span>
<a name="33" /><span class="True">      33:</span> <span class="k">     XXX block_new(DEFAULT_BLOCK_SIZE) returns NULL, that&apos;s passed on but</span>
<a name="34" /><span class="True">      34:</span> <span class="k">     XXX an exception is not set in that case).</span>
<a name="35" /><span class="True">      35:</span> <span class="k">  */</span>
<a name="36" /><span class="True">      36:</span>   <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="b">PyArena</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyArena_New</span><span class="f">(</span><span class="m">void</span><span class="f">)</span><span class="f">;</span>
<a name="37" /><span class="True">      37:</span>   <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span><span class="f">)</span> <span class="b">PyArena_Free</span><span class="f">(</span><span class="b">PyArena</span> <span class="f">*</span><span class="f">)</span><span class="f">;</span>
<a name="38" /><span class="True">      38:</span> 
<a name="39" /><span class="True">      39:</span>   <span class="k">/* Mostly like malloc(), return the address of a block of memory spanning</span>
<a name="40" /><span class="True">      40:</span> <span class="k">   * `size` bytes, or return NULL (without setting an exception) if enough</span>
<a name="41" /><span class="True">      41:</span> <span class="k">   * new memory can&apos;t be obtained.  Unlike malloc(0), PyArena_Malloc() with</span>
<a name="42" /><span class="True">      42:</span> <span class="k">   * size=0 does not guarantee to return a unique pointer (the pointer</span>
<a name="43" /><span class="True">      43:</span> <span class="k">   * returned may equal one or more other pointers obtained from</span>
<a name="44" /><span class="True">      44:</span> <span class="k">   * PyArena_Malloc()).</span>
<a name="45" /><span class="True">      45:</span> <span class="k">   * Note that pointers obtained via PyArena_Malloc() must never be passed to</span>
<a name="46" /><span class="True">      46:</span> <span class="k">   * the system free() or realloc(), or to any of Python&apos;s similar memory-</span>
<a name="47" /><span class="True">      47:</span> <span class="k">   * management functions.  PyArena_Malloc()-obtained pointers remain valid</span>
<a name="48" /><span class="True">      48:</span> <span class="k">   * until PyArena_Free(ar) is called, at which point all pointers obtained</span>
<a name="49" /><span class="True">      49:</span> <span class="k">   * from the arena `ar` become invalid simultaneously.</span>
<a name="50" /><span class="True">      50:</span> <span class="k">   */</span>
<a name="51" /><span class="True">      51:</span>   <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyArena_Malloc</span><span class="f">(</span><span class="b">PyArena</span> <span class="f">*</span><span class="f">,</span> <span class="b">size_t</span> <span class="b">size</span><span class="f">)</span><span class="f">;</span>
<a name="52" /><span class="True">      52:</span> 
<a name="53" /><span class="True">      53:</span>   <span class="k">/* This routine isn&apos;t a proper arena allocation routine.  It takes</span>
<a name="54" /><span class="True">      54:</span> <span class="k">   * a PyObject* and records it so that it can be DECREFed when the</span>
<a name="55" /><span class="True">      55:</span> <span class="k">   * arena is freed.</span>
<a name="56" /><span class="True">      56:</span> <span class="k">   */</span>
<a name="57" /><span class="True">      57:</span>   <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">int</span><span class="f">)</span> <span class="b">PyArena_AddPyObject</span><span class="f">(</span><span class="b">PyArena</span> <span class="f">*</span><span class="f">,</span> <span class="b">PyObject</span> <span class="f">*</span><span class="f">)</span><span class="f">;</span>
<a name="58" /><span class="True">      58:</span> 
<a name="59" /><span class="False">      59:</span> <span class="f">#</span><span class="n">ifdef</span> <span class="b">__cplusplus</span>
<a name="60" /><span class="False">      60:</span> <span class="f">}</span>
<a name="61" /><span class="True">      61:</span> <span class="f">#</span><span class="n">endif</span>
<a name="62" /><span class="True">      62:</span> 
<a name="63" /><span class="True">      63:</span> <span class="f">#</span><span class="n">endif</span> <span class="k">/* !Py_PYARENA_H */</span>
<a name="64" /><span class="True">      64:</span> <span class="f">#</span><span class="n">endif</span> <span class="k">/* Py_LIMITED_API */</span>
<a name="65" /><span class="True">      65:</span> </pre>
  </body>
</html>
